package com.demo.crm.springboot3security.service;

import java.util.List;

import com.demo.crm.springboot3security.entity.FormRelation;
import com.demo.crm.springboot3security.entity.enums.RelationType;
import com.mybatisflex.core.paginate.Page;

/**
 * 表单关系服务接口
 * 
 * 该接口提供了管理表单之间关系的相关操作，包括： - 创建和更新表单关系 - 查询表单关系 - 删除表单关系 - 批量操作表单关系
 */
public interface FormRelationService {

    /**
     * 保存表单关系
     * 
     * @param relation 要保存的表单关系对象
     * @return 保存后的表单关系对象（包含生成的ID）
     * @throws com.demo.crm.springboot3security.exception.FormRelationException.InvalidRelationException   当关系数据无效时
     * @throws com.demo.crm.springboot3security.exception.FormRelationException.DuplicateRelationException 当存在重复关系时
     */
    FormRelation save(FormRelation relation);

    /**
     * 删除指定ID的表单关系
     * 
     * @param id 要删除的表单关系ID
     * @throws com.demo.crm.springboot3security.exception.FormRelationException.RelationNotFoundException 当关系不存在时
     */
    void delete(Long id);

    /**
     * 根据ID查找表单关系
     * 
     * @param id 表单关系ID
     * @return 找到的表单关系对象，如果不存在则返回null
     */
    FormRelation findById(Long id);

    /**
     * 查找所有表单关系
     * 
     * @return 所有表单关系的列表
     */
    List<FormRelation> findAll();

    /**
     * 查找指定源表单的所有关系
     * 
     * @param sourceFormId 源表单ID
     * @return 该源表单的所有关系列表
     */
    List<FormRelation> findBySourceFormId(Long sourceFormId);

    /**
     * 查找指定目标表单的所有关系
     * 
     * @param targetFormId 目标表单ID
     * @return 该目标表单的所有关系列表
     */
    List<FormRelation> findByTargetFormId(Long targetFormId);

    /**
     * 分页查询表单关系
     * 
     * @param pageNumber 页码（从1开始）
     * @param pageSize   每页大小
     * @return 分页结果
     */
    Page<FormRelation> findByPage(int pageNumber, int pageSize);

    /**
     * 删除指定源表单的所有关系
     * 
     * @param sourceFormId 源表单ID
     */
    void deleteBySourceFormId(Long sourceFormId);

    /**
     * 删除指定目标表单的所有关系
     * 
     * @param targetFormId 目标表单ID
     */
    void deleteByTargetFormId(Long targetFormId);

    /**
     * 批量保存表单关系
     * 
     * @param relations 要保存的表单关系列表
     * @return 保存后的表单关系列表
     * @throws com.demo.crm.springboot3security.exception.FormRelationException.InvalidRelationException 当任何关系数据无效时
     */
    List<FormRelation> saveAll(List<FormRelation> relations);

    /**
     * 查找特定源表单和目标表单之间的所有关系
     * 
     * @param sourceFormId 源表单ID
     * @param targetFormId 目标表单ID
     * @return 符合条件的关系列表
     */
    List<FormRelation> findBySourceFormIdAndTargetFormId(Long sourceFormId, Long targetFormId);

    /**
     * 查找指定源表单的特定类型关系
     * 
     * @param sourceFormId 源表单ID
     * @param relationType 关系类型
     * @return 符合条件的关系列表
     * @throws com.demo.crm.springboot3security.exception.FormRelationException.InvalidRelationException 当关系类型无效时
     */
    List<FormRelation> findBySourceFormIdAndType(Long sourceFormId, RelationType relationType);

    /**
     * 查找指定目标表单的特定类型关系
     * 
     * @param targetFormId 目标表单ID
     * @param relationType 关系类型
     * @return 符合条件的关系列表
     * @throws com.demo.crm.springboot3security.exception.FormRelationException.InvalidRelationException 当关系类型无效时
     */
    List<FormRelation> findByTargetFormIdAndType(Long targetFormId, RelationType relationType);

    /**
     * 检查源表单和目标表单之间是否存在关系
     * 
     * @param sourceFormId 源表单ID
     * @param targetFormId 目标表单ID
     * @return 如果存在关系则返回true，否则返回false
     */
    boolean existsBySourceAndTargetForm(Long sourceFormId, Long targetFormId);

    /**
     * 批量创建表单关系
     * 
     * @param relations 要创建的表单关系列表
     * @throws com.demo.crm.springboot3security.exception.FormRelationException.InvalidRelationException 当任何关系数据无效时
     */
    void batchCreate(List<FormRelation> relations);

    /**
     * 批量更新表单关系
     * 
     * @param relations 要更新的表单关系列表
     * @throws com.demo.crm.springboot3security.exception.FormRelationException.InvalidRelationException 当任何关系数据无效时
     */
    void batchUpdate(List<FormRelation> relations);

    /**
     * 批量删除表单关系
     * 
     * @param ids 要删除的表单关系ID列表
     */
    void batchDelete(List<Long> ids);
}